header/src/main/java/org/zstack/header/vm/APICleanupVmInstanceMetadataEvent.java (1)

46-54: 建议在 __example__ 中补充 failedPrimaryStorageUuids 示例值。

新增字段已进入事件模型，但示例未覆盖，文档示例可读性会打折。

♻️ 建议修改

 public static APICleanupVmInstanceMetadataEvent __example__() {
     APICleanupVmInstanceMetadataEvent evt = new APICleanupVmInstanceMetadataEvent();
     evt.totalCleaned = 5;
     evt.totalFailed = 0;
     evt.failedVmUuids = java.util.Collections.emptyList();
+    evt.failedPrimaryStorageUuids = java.util.Collections.emptyList();
     return evt;
 }

As per coding guidelines, "API 类需要实现 example 方法以便生成 API 文档，并确保生成对应的 Groovy API Template 与 API Markdown 文件。"

Also applies to: 56-61

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@header/src/main/java/org/zstack/header/vm/APICleanupVmInstanceMetadataEvent.java`
around lines 46 - 54, The API example for APICleanupVmInstanceMetadataEvent is
missing a sample value for the new field failedPrimaryStorageUuids; update the
class's static __example__ method to populate failedPrimaryStorageUuids (e.g., a
list with one or more UUID strings) alongside the existing example fields so
generated Groovy template/Markdown include this new property; ensure the example
uses realistic UUID-format strings and the method returns the event instance
with failedPrimaryStorageUuids set.

header/src/main/java/org/zstack/header/vm/APICleanupVmInstanceMetadataMsg.java (1)

39-42: 建议在 __example__ 增加 cleanAllVmMetadata=true 的示例。

当前示例未覆盖新增参数场景，补充后更利于 API 文档与 SDK 使用者理解“全量清理”用法。

As per coding guidelines API 类需要实现 __example__ 方法以便生成 API 文档，并确保生成对应的 Groovy API Template 与 API Markdown 文件。

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@header/src/main/java/org/zstack/header/vm/APICleanupVmInstanceMetadataMsg.java`
around lines 39 - 42, Update the static example generator
APICleanupVmInstanceMetadataMsg.__example__ to include the new boolean option by
setting cleanAllVmMetadata = true in the returned msg (while keeping existing
vmUuids example), so the generated API docs show the “clean all metadata”
scenario; locate the __example__ method in APICleanupVmInstanceMetadataMsg and
assign msg.cleanAllVmMetadata = true before returning the msg.

plugin/localstorage/src/main/java/org/zstack/storage/primary/local/LocalStorageBase.java (1)

3633-3691: 建议：增加失败主机追踪以提高运维可见性

与类似的 ScanVmInstanceMetadataFromPrimaryStorageMsg 处理逻辑（第 3470-3557 行）相比，该方法存在以下不一致：

1. 缺少断开连接主机的追踪：Scan 方法显式追踪了断开连接的主机并在开始前将它们加入 failedHosts 列表，但此方法没有类似处理。

2. 缺少失败主机信息的反馈：当部分主机失败时，只记录了日志警告，但 reply 中没有包含失败主机的信息，不利于运维排查。

建议参考 Scan 方法的模式，追踪失败的主机列表：

♻️ 建议的改进

 private void handleCleanAllVmMetadataOnLocalStorage(final CleanupVmInstanceMetadataOnPrimaryStorageMsg msg) {
     CleanupVmInstanceMetadataOnPrimaryStorageReply reply = new CleanupVmInstanceMetadataOnPrimaryStorageReply();

+    List<String> allHostUuids = SQL.New(
+                    "select h.hostUuid from LocalStorageHostRefVO h, HostVO host" +
+                            " where h.primaryStorageUuid = :psUuid" +
+                            " and h.hostUuid = host.uuid", String.class)
+            .param("psUuid", self.getUuid())
+            .list();
+
     List<String> connectedHostUuids = SQL.New(
                     "select h.hostUuid from LocalStorageHostRefVO h, HostVO host" +
                             " where h.primaryStorageUuid = :psUuid" +
                             " and h.hostUuid = host.uuid" +
                             " and host.status = :hstatus", String.class)
             .param("psUuid", self.getUuid())
             .param("hstatus", HostStatus.Connected)
             .list();
     if (connectedHostUuids.isEmpty()) {
         logger.warn(String.format("[MetadataCleanup] cleanAll: no connected host found for local ps[uuid:%s]", self.getUuid()));
         reply.setCleanedCount(0);
         bus.reply(msg, reply);
         return;
     }

+    // Track disconnected hosts as failed upfront
+    List<String> failedHosts = Collections.synchronizedList(new ArrayList<>());
+    List<String> disconnectedHostUuids = new ArrayList<>(allHostUuids);
+    disconnectedHostUuids.removeAll(connectedHostUuids);
+    failedHosts.addAll(disconnectedHostUuids);
+
     AtomicInteger totalCleaned = new AtomicInteger(0);
     new While<>(connectedHostUuids).all((hostUuid, com) -> {
         // ... existing code ...
+                `@Override`
+                public void fail(ErrorCode errorCode) {
+                    logger.warn(...);
+                    failedHosts.add(hostUuid);
+                    com.addError(errorCode);
+                    com.done();
+                }
     }).run(new WhileDoneCompletion(msg) {
         `@Override`
         public void done(ErrorCodeList errorCodeList) {
             // ... existing code ...
+            if (!failedHosts.isEmpty()) {
+                reply.setFailedStorages(failedHosts);  // 如果 reply 支持此字段
+                logger.warn(String.format("[MetadataCleanup] cleanAll partial failure, failedHosts=%s", failedHosts));
+            }
             bus.reply(msg, reply);
         }
     });
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@plugin/localstorage/src/main/java/org/zstack/storage/primary/local/LocalStorageBase.java`
around lines 3633 - 3691, The handleCleanAllVmMetadataOnLocalStorage method
lacks tracking/reporting of failed or disconnected hosts; update it to mirror
the ScanVmInstanceMetadataFromPrimaryStorageMsg pattern by creating and
maintaining a failedHosts list, add disconnected host UUIDs to it when
connectedHostUuids is empty or hosts are not Connected, push host UUIDs into
failedHosts when backend preparation fails in
getHypervisorBackendFactoryByHostUuid or when bkd.handle(...) fails in the
ReturnValueCompletion.fail callback, and include this failedHosts information in
the CleanupVmInstanceMetadataOnPrimaryStorageReply (set an error or a
failedHosts field) before bus.reply(msg, reply) so callers/operators can see
which hosts failed.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

plugin/localstorage/src/main/java/org/zstack/storage/primary/local/LocalStorageKvmBackend.java (1)

3955-3957: 建议对 cleanedCount 增加非负保护。

Line 3956 直接信任 agent 返回值，若异常返回负数会污染上层清理统计；建议在赋值前做边界收敛。

可选修正示例

             public void success(CleanupVmMetadataRsp rsp) {
                 CleanupVmInstanceMetadataOnPrimaryStorageReply reply = new CleanupVmInstanceMetadataOnPrimaryStorageReply();
-                reply.setCleanedCount(rsp.cleanedCount);
+                reply.setCleanedCount(Math.max(rsp.cleanedCount, 0));
                 completion.success(reply);
             }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@plugin/localstorage/src/main/java/org/zstack/storage/primary/local/LocalStorageKvmBackend.java`
around lines 3955 - 3957, The code sets reply.setCleanedCount(rsp.cleanedCount)
directly and should guard against negative values from the agent; change the
assignment in the block that constructs
CleanupVmInstanceMetadataOnPrimaryStorageReply so you sanitize rsp.cleanedCount
(e.g., use a non-negative clamp like Math.max(0, rsp.cleanedCount) or check for
null/invalid and default to 0) before calling reply.setCleanedCount(...), then
call completion.success(reply).

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes